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FORWARD 

The R-Time 8 now adds another dimension to the SpartaDOS 
Construction Set family which began with SpartaDOS version 1.1 
and the US Doubler. Although the TD/XTD/TSET commands have 
been around for quite some time, they have been modified several 
times as problems arose. Their method of time/date support 
simply did not allow the flexibility that is now needed. As part of 
our ongoing development of SpartaDOS, we have developed a new 
SpartaDOS version which has built in TD and TSET functions. 
Accompanying the R-Time 8 is this new SpartaDOS version 3.2. 

The R-Time 8 package includes: 1) this supplement; 2) the R-Time 
8 cartridge; 3) a double sided diskette with SpartaDOS 3.2 and 
updated command files on the front side. The back side is in Atari 
DOS 2 format and has the R-Time 8 generic 'Z:' handler 
(RTIME8.COM) and its source code (RTIME8.SRC). 

The SpartaDOS Construction Set package includes: 1) a diskette 
containing the standard SpartaDOS version 1.1 on the front and 
public domain games with the LOGOMENU program on the back 
side; 2) a diskette containing both SpartaDOS version 2.3 and 3.2 
with their supporting command files; 3) this supplement; 4) the 
SDSC Owner's Manual. If you purchased the US Doubler, you 
receive the 2 US Doubler chips along with the SDCS package. 

This manual is supplied with both the latest SpartaDOS 
Construction Set and the R-Time 8 package. The divisions of the 
manual and their contents are as follows: 

Chapter 1— Introduction to the R-Time 8 
Chapter 2— Overview of SpartaDOS 3.2 
Chapter 3— Commands Added to SpartaDOS 3.2 
Chapter 4— Update on the Technical Structure 
Chapter 5— The Time/Date 'Z:' Handier Functions 
Chapter 6— Using the Supra Hard Disk Interface with 
SpartaDOS 



CHAPTER 1— INTRODUCTION TO THE R-TIME 8 

This chapter is a brief introduction to the R-Time 8 cartridge. 
Explanations are included on how to use the R-Time 8 files with 
six different versions of DOS, and which versions of DOS you may 
use with your computer. 



Installation (Plugging it in) 

Install the R-Time 8 cartridge as you would install any other 
cartridge for the Atari 8 bit computer line. The flap on top with the 
ICD logo faces toward the front of the 800 and 800XL computers. 
On the Atari 800 computers (which have both left and right slots), 
you may use whichever slot is most convenient (normally the right 
since most other cartridges use the left slot). Notice that the top 
of the R-Time 8 cartridge has an expansion port. You may use it to 
plug in your language cartridge (Pilot, ACTION, BASIC XE, etc.) on 
top of the R-Time 8. 



Booting Your Computer 

First you must choose which DOS to use. Although any DOS 
should work, your choice governs the flexibility and ease of use of 
the R-Time 8. For example, if you use Atari DOS 2.5, you lose the 
powerful TIME, DATE, and TD commands supported from 
SpartaDOS 3.2. Most importantly, no version or derivative of Atari 
DOS 2 supports time and date stamping of files. This was the 
whole premise for making the R-Time 8— to time/date stamp 
SpartaDOS files. A standard 'Z:' handler is implemented for which 
ever DOS you choose. With this interface to the cartridge, you may 
use BASIC (or whatever language you wish to use) to access the 
R-Time 8 for a wide variety of applications. 
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DOS Choices and Their Use with the R-Time 8 

Sparta DOS 3.2 (for use with 800XL, 1200XL, 130XE and most 
operating systems) 

If you have one of these computers, this is the choice to make. 
The command processor has the commands TIME, DATE, and TD 
built in, which allow you to read, and set the time and date. TD 
allows you to turn on and off a time/date display line; however, the 
actual handler code (TDLINE) must be loaded before the first use 
of the internal TD command. To install the 'Z:' handler, you must 
enter the command ZHAND. 

NOTE: ZHAND is only necessary if you wish to address the 
R-Time 8 as the 'Z:' device. This is generally for easy access from 
BASIC or other language programs. 

Sparta DOS 2.3 (for use with 800XL, 130XE using the standard OS 
only) 

This version of SpartaDOS has a MEMLO of under $E00 which 
gives almost an extra 4000 bytes of free user memory over Atari 
DOS. Use the external TD or XTD commands to provide the 
interface between SpartaDOS 2.3 and the R-Time 8. (The external 
TD command also provides the time/date display line.) Neither of 
these supply the 'Z:' handler, but they take less memory. An 
alternative to TD/XTD is the RTIME8 command. This supplies the 
'Z:' handler as well as the DOS to R-Time 8 interface. The TSET 
command is used to set the time or date and may be used while 
either RTIME8 or TD/XTD is installed. 

SpartaDOS 1.1 (works with any 8-bit Atari computer with at least 
32K RAM) 

If you have an 800 or need a translator, use this version; if not, it is 
better to use version 3.2 or 2.3. The same commands work for this 
version as for SpartaDOS 2.3. This version of DOS has a much 
higher MEMLO than 2.3 or 3.2 and is not capable of reading Atari 
DOS 2 diskettes directly. There are several different 1.1 versions 
(e.g. NOCP, NOWRITE, SPEED, STANDARD) which work around its 
deficiencies. 
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Use one of the following DOS types if you don't have 
Sparta DOS 

Atari DOS 2 or 2.5 (and its many followers i.e. MYDOS, TOPDOS, 
SMARTDOS etc.) 

You must rename the RTIME8.COM file to AUTORUN.SYS and 
boot your DOS 2 diskette. (The back side of the diskette supplied 
with the R-Time cartridge is an Atari DOS 2 format with the 
RTIME8.COM handler and the RTIME8.SRC source file.) The 
handler will load and relocate itself at MEMLO. 

NOTE: the time/date display line will automatically be turned off 
when you enter DOS (by the DOS command from BASIC). 

DOS XL (by OSS) 

To install the R-Time 8 handler, enter the command RTIME8 from 
the command processor. Since this is a CP (Command Processor) 
type of DOS, the time/date display line will remain on (as in 
SpartaDOS) when you enter DOS (by the DOS command from 
BASIC). 

Atari DOS 3 

If you have this DOS, we strongly recommend that you do not use 
it anymore. Go out and purchase the SpartaDOS Construction Set. 
Atari DOS 3, a product of the old Atari, will become a nightmare 
since: 1) it is not supported by Atari or any software company; 
2) it is very difficult to convert DOS 3 files to any other disk 
operating system. 

Some Examples Using the 'Z:' Handler with BASIC 

These examples all assume that you have BASIC installed in your 
computer (either internal or a cartridge) and wish to access the 
R-Time 8 in a program. For more details on the 'Z:' handler 
functions, see Chapter 5 of this supplement. To install the 'Z:' 
handler, choose a DOS and perform one of the following 
operations depending on your selection: 
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Sparta DOS 3.2 

Boot the DOS and enter the commands: 
TDLINE 
ZHAND 
CAR 

SpartaDOS 2.3, 1.1, DOS XL 

Boot the DOS and enter the commands: 
RTIME8 
CAR 

Atari DOS 2 (and family) 

Move RTIME8.COM to your DOS diskette and rename it to 

AUTORUN.SYS. 

Now boot that diskette; the handler will install 

automatically. 

Turning the Clock On and Off 

To turn the clock display on, enter the following command (from 
BASIC): 

XIO 38,#1,0,0,"Z:" 

An extra display line will appear on top of the screen containing 
the correct time and date. Most programs from BASIC should 
work with this display line turned on; however, there are many 
exceptions. Practically all programs that use custom display lists 
or vertical blank routines will not work correctly. In most cases, 
the display line will simply be lost. 

One inherent problem with Atari DOS 2 is the non-resident nature 
of the DUP.SYS program. The time/date display can't be on while 
using DUP (because DUP loads on top of the interrupt handler). 
Since it is inconvenient to always turn the display off before 
typing 'DOS', it is automatically done for you. There is absolutely 
no problem when using SpartaDOS or OSS DOS XL The time/date 
will remain on since no DUP.SYS is needed. 

To remove the time/date line from the display, enter the command: 
XIO39,#1,0,0,"Z:" 
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Reading the Clock Using BASIC 

Your BASIC programs (or any language) may read the time and 
date in either formatted or unformatted form. This is 
accomplished by performing an XIO call followed by several GETs 
or an INPUT on an open IOCB. For example, to read the formatted 
time, type and run the program: 

10 DIM TIME$(10) 

20 OPEN #1, 4,0, "Z:" 

30XIO32,#1,0,0,"Z:" 

40 INPUT #1, TIMES 

50 PRINT "Current Time is ";TIME$ 

60 CLOSE #1 

Setting the Clock 

Your BASIC program may set the time or date by performing an 
XIO and a sequence of three PUT statements. The following is an 
example of setting the date: 

10 OPEN #1, 8,0, "Z:" 

20 PRINT "Enter Date (MM,DD,YY) "; 

30 INPUT MONTH, DAY, YEAR 

40XIO35,#1,0,0,"Z:" 

50 PUT #1,DAY : PUT #1, MONTH : Put #1,YEAR 

60 CLOSE #1 

When setting the time, the hour must be given using a 24 hour 
clock where 12:00 midnight is 0, 12:00 noon is 12, 4:00 PM is 16, 
etc. The order of the PUT's is important. For date, it is: day, month, 
year; for time it is: hour, minute, second. 



R-Time 8 Use from Sparta DOS 

To use R-time 8 with SpartaDOS version 3.2, study the commands 
in Chapter 3 of this supplement. To use it with version 1.1 and 2.3, 
review Chapter 12 and Appendix D in the SpartaDOS Construction 
Set Owner's Manual. For R-Time 8 support of Bulletin Board 
Construction Set 1.6 or earlier, use SpartaDOS version 2.3 and the 
XTD handler. 
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R-Time 8 Access from Machine Language 

Although we strongly recommend that programmers using a 
standard DOS should access the R-Time 8 through the 'Z:' handler, 
we have included the source code for RTIME8 (RTIME8.SRC) on 
the back side of the R-Time 8 distribution diskette (Atari format). 
This gives detailed information on the inner workings of the clock 
chip to anyone familiar with machine language programming. Also 
refer to Chapter 4 of this supplement for information on the 
TIME/DATE vectors of SpartaDOS 3.2. 



R-Time 8 Maintenance and Service 

This accurate timing device has been built to supply you with 
years of trouble free service. The accuracy is determined by the 
frequency of the crystal at location Y1 and the adjustor at YC1. To 
open the case, carefully pry it apart equally at both ends with a 
flat blade screwdriver. To adjust for greater accuracy turn the 
small slot at the center of YC1 slightly to the right or left. If 
adjustment is needed, calibrate the R-Time 8 once a week with an 
accurate watch and adjust accordingly if it is gaining or losing 
seconds. It should be possible to get very close with this method 
and a little patience. Battery life is calculated for 3-5 years. The 
battery is a 200mah 3 volt Lithium cell. Replacement batteries are 
currently available for $5.00 including shipping. Full service 
including repair, calibration, and battery replacement is currently 
$20. This does not include damage due to abuse. 



CHAPTER 2— OVERVIEW OF SPARTADOS 3.2 

This chapter briefly describes the changes between SpartaDOS 
3.2 and SpartaDOS 2.3. Improvements have been made in the 
following areas: 

• Better time/date support (internal TD, TIME, DATE commands) 

• Internal R-TIME 8 interface 

• Internal JIFFY clock interface (for non-R-TIME 8 users) 

• Internal 32 character keyboard buffer (and KEY command) 

• Automatic mini-buffer system for fast single byte PUT/GET 

functions 

• New vectors added for machine language support 

• Control returned to DOS if DOS was active during RESET 

• Supports both a STARTUP.BAT and an AUTORUN.SYS file 

• Compatible with BASIC XE, 1200XLs, and many modified 
operating systems 

• BASIC ON/OFF command operation from within a batch file 
(not end only) 

• NOISY I/O flag recognized 

• Support for the Supra Hard Disk Interface 

• All command entry in upper or lower case 

• Full read capability for Atari DOS 2.5 type dual density format 



Internal Real Time Support 

Three new internal commands, time/date support vectors, an 
internal clock, and access to the R-Time 8 cartridge, have been 
added for convenience and easy access. 

Operating on the jiffy counter (at location $12-$14), the internal 
clock determines the number of jiffies (1/60th sec) between the 
current and the last access. Time is then added to the internal 
clock based on this difference. Unfortunately a RESET zeros the 
jiffy counter, thus the time between the last access and RESET is 
lost! The command TDLINE fixes this problem by updating the 
internal clock each half second while displaying the time/date on 
the top of the display. Unfortunately this method must use the 
vertical blank interrupt which runs the risk of interfering with other 
user applications. The TIME command from older SpartaDOS 
versions is similar to TDLINE in its inherent problems. 
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If you have an R-Time 8 cartridge installed, SpartaDOS 3.2 will 
recognize it and use the R-Time 8 in place of the internal jiffy 
clock. 

The new internal TIME and DATE commands are used to 
set/display the time and date. The new internal TD command is 
used to turn the time/date display line on and off (i.e. TD ON or TD 
OFF) once TDLINE has been installed. 

The old external time/date support commands (TD, TSET, XTD, 
TIME, SET) have not been changed. They may still be used with 
SpartaDOS 2.3 and 1.1. The reason for this will become apparent 
later. 



Keyboard Buffer 

A 32 byte keyboard buffer is now standard. The repeat rate has 
been doubled for faster operation. The keyboard buffer allows you 
to type ahead of the computer (up to 32 characters) even while 
disk I/O is occurring. You may disable this keyboard buffer by the 
KEY OFF command. (Use KEY ON to turn the buffer back on.) 

Mini-buffering 

Due to the nature of the CIO and the large database needed for 
SpartaDOS to operate, single GET/PUT operations tended to be 
slow. SpartaDOS 3.2 now contains mini-buffering that allows 
these operations to be performed faster. This also means faster 
INPUT/PRINT operations on disk files. (Mini-buffering is not used 
with Atari DOS 2 formatted diskettes.) 

RESET 

Now when you press RESET while in DOS with a cartridge 
present, control will remain with DOS. This also solves the conflict 
involving the warm start of BASIC that may have occurred under 
unusual situations. Optionally, AUTOBAT.COM can be used which 
causes a particular batch file to execute after pressing RESET. 



8 



Chapter 2— Overview of SpartaDOS 3.2 

AUTORUN.SYS and STARTUP.BAT 

When SpartaDOS is booted, it will try to load an AUTORUN.SYS 
file. If successful, this file will run and then pass control to the 
cartridge. Otherwise, SpartaDOS will try starting a STARTUP.BAT 
file. If successful, control will pass to the command processor of 
DOS; otherwise, control will pass to the cartridge. 



BASIC XE 

The original reason for writing version 3.2 was to be compatible 
with BASIC XE. This has been done, but resulted in some major 
changes. First MEMLO had to be drastically increased (to just 
below Atari DOS 2). As long as MEMLO had to be increased, it 
may as well be pushed up near Atari DOS 2 with many extras 
added. 



Supra Hard Disk Interface 

Support for the Supra Hard Disk Interface has been added, 
including the new BYPASS command which allows the use of 
floppy drives as 1 & 2, with the hard disks as 3 & 4. This differs 
from the default set up with a 'fake' floppy as 1, a real floppy as 2, 
and the hard disks as 3 & 4. 



DOS 2.5 Extended Read Capability 

SpartaDOS version 3.2 can directly read all sectors on an Atari 
DOS 2.5 formatted diskette in dual density. This means you can 
boot SpartaDOS 3.2, insert a full Atari DOS 2.5 dual density 
diskette, and RUN or COPY files from the directory which extend 
past sector 720. You still cannot write to this area of the diskette, 
however, read capability should be sufficient for most users. 
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CHAPTER 3— COMMANDS ADDED TO SPARTADOS 3.2 

The following is a summary of the new commands added to 
SpartaDOS 3.2 



TIME Command 

Purpose 

This command displays the current time and allows you to set the 
time. 

Syntax 

TIME 

Type and Restrictions 

Internal under CP version 3.2 

(This is totally different from the old external TIME command) 

Remarks 

This command produces the following output: 

Current time is 12:34:56pm 
Enter new time: 

You may enter the new time or press RETURN if you don't want to 
set a new time. Enter the time in the format: "hh:mm:ssx" where 
'hh' is the hours, 'mm' is the minutes, 'ss' is the seconds and 'x' is 
an 'A' or a 'P' to distinguish between AM and PM. 

NOTE: time is entered using a 12 hour clock rather than a 24 hour 
clock as in the plder commands. 
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DATE Command 

Purpose 

This command displays the current date and allows you to set the 
date. 

Syntax 
DATE 

Type and Restrictions 

Internal under CP version 3.2 

Remarks 

This command produces the following output: 

Current date is 10/07/85 
Enter new date: 



You may enter the new date or press RETURN if you don't want to 
set a new date. Enter the date in the format: "mm/dd/yy" where 
'mm' is the month, 'dd' is the date, and 'yy' is the year. 



TD Command 

Purpose 

This command allows you to turn the time/date display line on and 
off. 

Syntax 

TDONorTDOFF 

Type and Restrictions 

Internal under CP version 3.2 

(This is totally different from the old external TD command) 

Remarks 

The time/date display line is not supported internally by 
SpartaDOS. If you want the time/date display, you must first enter 
the TDLINE command to install the handler. This is explained 
further in the description of the time/date vectors. 
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TDLINE Command 

Purpose 

This command installs the time/date display line handler. The 
internal TD command controls this handler. 

Syntax 

TDLINE 

Type and Restrictions 

External under CP version 3.2 

(This command may not be used with earlier versions) 

Remarks 

This command installs a handler into the system that gets acces- 
sed by the SpartaDOS time/date vectors. The functions TDON and 
FMTTD are provided by this handler. The TDON function causes 
this handler to patch itself into the vertical blank interrupt. During 
the interrupt, it calls the FMTTD function through SpartaDOS 
(returns the formatted time/date line), converts it to display format, 
and then displays it on the expansion top line. 

RTIME8 Command 

Purpose 

This command installs the routines needed to access the R-TIME 
8 cartridge for SpartaDOS versions 2.3 and 1.1. It is also used with 
Atari DOS as an AUTORUN.SYS file. RTIME8 contains the ZHAND 
and TDLINE functions. 

Syntax 

RTIME8 

Type and Restrictions 

External under CP versions 2.3, 1.1, and as AUTORUN.SYS with 
Atari DOS 

Remarks 

The RTIME8 installs the 'Z:' handler into the system. Under 
SpartaDOS 2.3 and 1.1, it updates TIMER/DATER (in COMTAB) for 
file time/date stamping. It is not to be used in conjunction with TD 
or XTD. It is provided for the 'Z:' handler compatibility. 
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NOTE: RTIME8 will also work with version 3.2 but it is preferable 
to use ZHAND and TDLINE instead. RTIME8 uses 178 more bytes 
than ZHAND and TDLINE combined. Also, ZHAND and TDLINE 
work with both the internal clock and the R-TIME 8 cartridge under 
version 3.2 (the vectors are there). RTIME8 only supports the R- 
TIME 8 cartridge but works with all versions of SpartaDOS. 



ZHAND Command 

Purpose 

This command installs a 'Z:' handler that allows easy access to 
time/date functions from BASIC. 

Syntax 

ZHAND 

Type and Restrictions 

External under CP version 3.2 

(This may not be used with earlier versions) 

Remarks 

This command installs a device handler that provides an interface 
from a high level language to time/date functions. This handler 
converts requests from the CIO into calls to the SpartaDOS 
time/date vectors and visa versa. This may be used with either the 
R-Time 8 cartridge or the internal time/date in SpartaDOS. Further 
documentation on the 'Z:' handler is provided later is this 
document. 



KEY Command 

Purpose 

This command enables or disables the internal keyboard buffer. 

Syntax 

KEY OFF or KEY ON 

Type and Restrictions 

Internal under CP version 3.2 
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Remarks 

You will normally want the keyboard buffer on. It turns out to be 
quite handy. (Use it for a while.) In rare cases, the keyboard buffer 
may interfere with a software program. If this happens, simply 
disable the buffer by the KEY OFF command. 



RAM DISK Command 

Purpose 

These commands install a RAMDISK device in place of a physical 
disk drive. Since these commands depend on specific hardware, 
the correct RAMDISK command must be used or an error will 
result. 

Syntax 

RD Dn: [/NE] 
RD260 Dn: [/N] 

Type and Restrictions 

External under all CP versions— command must match hardware 

Remarks 

These new RAMDISKs support hardware modifications which can 
be made to the 800XL, 1200XL, and 130XE to provide large 
RAMDISKs. Both commands format the RAMDISK automatically 
in the 128 byte sectors unless the 7N' parameter is used. 

RD.COM supports the standard 130XE, the 130XE with 64K RAM 
upgrade (from Ron Boling), and the new 256K RAMBO XL upgrade 
for the 800XL and 1200XL computers. The RAMBO XL upgrade is 
available from ICD either installed or in kit form. RD.COM, used 
with the RAMBO XL, gives a 192K RAMDISK which holds a full 
double density disk! RAMBO XL also makes your 800XL or 1200XL 
fully compatible with BASIC XE and other 130XE programs that 
take advantage of its extra memory! 

The 7E' parameter (supported with RD.COM only) reserves the first 
64K bank area for programs which use the extended memory of 
the 130XE (such as BASIC XE). For example: 'RD D2: IE' will install 
a 128K RAMDISK when using an 800 XL modifed with RAMBO XL 
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RD260.COM supports the 800XL RAM upgrade to 256K as 
published in the September 1985 BYTE magazine by Claus 
Buchholz. It is used like RD.COM and gives a 192K RAMDISK! This 
upgrade banks the lower 32K of memory unlike RAMBO XL which 
banks memory from $4000 - $7FFF like the 130XE. 

The 7N' parameter indicates that the RAMDISK is not to be 
formatted. This allows you to reboot the system and be able to 
retrieve the data that was in the RAMDISK. 

CAUTION: you may not power down the computer to reboot; it 
must be done with a RESET that causes a reboot (coldstart). This 
is accomplished by setting memory location $244 to a non-zero 
value and then pressing RESET. This is very useful for running a 
BBS from the RAMDISK. If the DOS crashes, you may be able to 
recover everything from the RAMDISK. 

SCOPY Command 

Purpose 

This command is used: to perform a straight sector copy, to 
compact an entire diskette into a file on another diskette, or to 
expand a file onto an entire diskette. 

Syntax 

SCOPY Dn:[[path>]fname] [/UR] Dn:[[path>]fname] [/UR] 

Type and Restrictions 

External under all CP versions 

Remarks 

SCOPY is a sector copier that has 3 modes of operation. It can do 
a disk to disk copy (like DUPDSK except that it formats the 
destination and it copies all sectors— this means it will copy Atari 
DOS 2 diskettes also). The other two modes of operation allow 
either: the compaction of an entire diskette to a file on a 
destination diskette, or the creation of a destination diskette from 
a previously compacted file. This is an easy method for making 
multiple copies of the same diskette (non-copy protected) using a 
RAMDISK. (In fact, this is how ICD creates its distribution 
diskettes.) 
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An example of disk to disk copy using a single US Doubler 1050 
drive follows: 

SCOPYD1: /U D1: /U 

This will cause a US sector skew diskette to be duplicated. (Leave 
out the 7U' when copying standard Atari DOS diskettes.) For 
multiple disk duplication using a RAMDISK and a single drive, a 
typical pair of batch files would be: 

RDD3: 

COPY SCOPY.COM D3: 

COPY BAT2.BAT D3: 

D3: 

; Insert diskette to copied in drive 1 

PAUSE 

SCOPYD1: /U D3:MYDISK 

-BAT2 

; Insert destination diskette in drive 1 

PAUSE 

SCOPY D3:MYDISK D1: /U 

-BAT2 

The second group of commands would be in the batch file 
'BAT2.BAT'; the first group would be 'BAT1.BAT'. This sequence 
will use 'D1:' as source and destination while using 'D3:' as a 
temporary drive. 

Note that SCOPY with NOT prompt in this sequence, thus the 
PAUSE command is used for the switching of diskettes in drive 1. 
You are prompted when performing drive to drive duplication as in 
the first example. 

For more information about batch files and how they work, see 
Chapter 14 in the SpartaDOS Construction Set Owner's Manual. 
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The mode of operation is strictly determined by the syntax of the 
command. The first disk/file is always the source and the second 
disk/file is always the destination of the operation (as is true with 
the COPY command). The three modes of operation are basically: 

disk to disk (simple sector copy) 
disk to file (compact diskette to file) 
file to disk (expand file to diskette) 

If a file name follows the 'Dn:', then that item is considered a 
compacted 'file'; with no filename, it is considered a 'disk'. A 'file 
to file' operation is illegal with SCOPY. 

The destination diskette is automatically formatted in the same 
density as the source disk was. The compacted file stores density 
information from the original disk it was created from. It does not 
matter what density the file resides on. Skew may be changed 
between US skew and standard Atari skew with the 7U' parameter 
described later. 

CAUTION: for disk to file and file to disk copies, no prompt is 
given; the operation is performed without intervention. Always 
make sure your destination disk can be formatted. (You will lose 
all previous information stored on it.) For disk to disk copies, you 
are prompted for source and destination diskettes as required. 

A 'disk' parameter may be followed by either a 7R' or 7U' 
parameter. The 7U' indicates that the diskette is US Doubler 
sector skew (for source) or is to be formatted in US sector skew 
(for destination). The 7R' parameter indicates that the diskette is 
really a RAMDISK. Only the RD.COM RAMDISK will act as a 'disk' 
with SCOPY. RD.COM creates a RAMDISK which is a complete 
model of a true disk drive. (It allows formatting, configuring, read 
configuration, and status commands.) The other RAMDISK 
handlers do not. Always use a 'space' as the delimiter between 
the device or filename and the slash (I) before the parameter. 

When using SCOPY, the copy process is performed as efficiently 
as possible. This means that if a drive contains a US Doubler and 
the diskette is not in US skew, SCOPY will adjust and optimize for 
fastest copy time. SCOPY will work with single, double, and 1050 
dual density diskettes. It is not intended for the specialty (eight 
inch or double sided) drives. 
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Chapter 3— Commands Added to SpartaDOS 3.2 
BYPASS Command 

Purpose 

This is a special command for the Supra Hard Disk Interface to 
allow the use of a floppy drive 1. 

Syntax 

BYPASS 

Type and Restrictions 

External under CP version 3.2 

Remarks 

This command is similar to the RAMDISK commands in that it will 
knock out the partitioned hard disk drive 1 and replace it with 
floppy drive 1 (assuming there is a physical floppy drive 
configured as 1). BYPASS patches itself into the SIO vector (of 
SpartaDOS) and checks for a drive 1 access. If so, then it passes 
control directly to the SpartaDOS serial I/O routines, thus the front 
end parallel I/O is skipped. BYPASS is needed if you wish to use a 
floppy drive a #1 rather than the drive 1 partition of the hard disk. 

CAUTION: If used from a batch file, make sure that the batch file 
is running from a drive other than drive 1. 

AUTOBAT Command 

Purpose 

AUTOBAT causes the specified batch file to be run whenever 
RESET is pressed. 

Syntax 

AUTOBAT [Dn:][path>]fname[.ext] 

Type and Restrictions 

External under CP version 3.2 

Remarks 

This command patches itself into the SpartaDOS INIT vector (refer 
to the technical structure update) to cause control to be passed to 
the specified batch file after RESET is pressed. Refer to Chapter 
14, 'Input/Output Redirection' in the SpartaDOS construction Set 
Owner's Manual for information about batch files. 
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CHAPTER 4— UPDATE ON TECHNICAL STRUCTURE 

Another version of SpartaDOS. . .why not? Actually, the major 
reason we decided to design another version of SpartaDOS was to 
achieve compatibility with BASIC XE which was released right 
after SpartaDOS version 2.3 came out. The actual problem was 
that BASIC XE was determined to use the memory at 
$C000-$CBFF and $D800-$DFFF which was already occupied by 
SpartaDOS 2.3. Since everybody seems to like BASIC XE 
(including us), it was decided that we would give up that area and 
move the code down to low memory. End of story? — no, of course 
not. As long as MEMLO had to be pushed up, we may as well start 
adding features. . . and add we did. . . 



SpartaDOS Time/Date and other Vectors 

SpartaDOS 3.2 contains many vectors pertaining to the setting, 
reading, displaying of the time and date, executing command 
lines, initializing the system and many more. These vectors are 
contained in the RAM under the operating system starting at 
address $FFC0. They may be accessed by the following 
instructions: 



Ida $D301 
pha 

and #$FE 

sta $D301 

jsr VGETTD 
pla 
sta $D301 ; restore the port (enable OS) 



PIA 

save old value of port on stack 

set bit to OFF 

enable RAM under the OS 

call routing at $FFC0 



These functions each contain a jump (JMP) instruction to the 
appropriate function. If a function is not initially supported (as in 
TDON), the vector will contain a SEC and RTS instruction rather 
than a JMP. The following vectors are currently supported: 
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Chapter 4 — Update on Technical Structure 

VGETTD($FFCO) 

This function returns the current time/date at TIMER 
and DATER (locations at COMTAB— see page 110 of 
the SpartaDOS manual). On return, the carry is SET if 
the function failed. When a file is opened for write, 
SpartaDOS makes a call here to update TIMER/DATER 
so it can move this data into the directory entry. Also 
the TIME and DATE internal commands make calls 
here to get the current time. TDLINE and ZHAND also 
use this vector. 

VSETTD ($FFC3) 

This function sets the time/date. On entry, the new 
time and date are at TIMER and DATER (locations at 
COMTAB— see page 110 of the SpartaDOS manual). On 
return, the carry is SET if the function failed. This 
vector is used by the commands TIME, DATE, and the 
ZHAND set functions. 

VTDON ($FFC6) 

This function turns the time/date display line on or off. 
On entry, the Y register contains if to turn the line off, 
or 1 if to turn the line on. On return, the carry is SET if 
the function failed. This function is not supported 
internally by SpartaDOS. The TDLINE handler patches 
into this vector for use by the TD command along with 
the ZHAND functions 38 and 39. (See the TDLINE 
command.) 

VFMTTD ($FFC9) 

This function returns the formatted time/date line into 
a user supplied buffer. On entry, the X and Y registers 
contain the high and low byte of the buffer address 
respectively. On exit, the carry is SET if the function 
failed. This function is not supported internally by 
SpartaDOS. The TDLINE handler patches into this 
vector for use by TDLINE and ZHAND routines. (See 
the TDLINE command.) 
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Chapter 4— Update on Technical Structure 

VINITZ ($FFCC) 

This vector is called after SpartaDOS has finished 
initializing itself after a RESET occurs. The command 
AUTOBAT patches into this vector to start a batch file 
right after RESET. (By initialization, we mean as a 
result of making a call through DOSINI— e.g. JMP 
(DOSINI). The OS monitor routine calls this vector 
before it enters a cartridge or DOS.) 

VINITZ2 ($FFCF) 

This vector is called after SpartaDOS has finished 
initializing itself after a NON-RESET occurs. Several 
SpartaDOS commands (such as SPCOPY and 
UNERASE) will initialize DOS before and after they 
perform their function. They do this by jumping 
through the DOSINI vector as does the OS monitor 
routine after a RESET. 

VXCOMLI ($FFD2) 

This vector calls the command processor to execute a 
command line given at LBUF. BUFOFF should be on 
entry. Any errors that may occur as a result of 
executing the command line shall be printed as usual. 
No prompts are printed before or after command 
execution. This is the method that a future DUP.SYS 
for SpartaDOS could use to perform its functions. 

VCOMND($FFD5) 

This vector calls the main command processor 
program entry point. You may patch into this vector if 
you wish to supply your own command processor. (The 
current one simply prints the prompt, inputs a line, 
calls VXCOMLI, and jumps back to the beginning.) This 
is the method DUP.SYS uses to gain entry from a DOS 
command in BASIC. 

VPRINT ($FFD8) 

This vector points to the SpartaDOS general print 
routine. The calling method is: 
JSR VPRINT 
DB 'This is a message',$9B,-1 
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Chapter 4— Update on Technical Structure 

VKEYON ($FFDB) 

This function turns the keyboard buffer on or off. On 
entry, the Y register contains if to turn the buffer off, 
or 1 if to turn the buffer on. This function is supported 
internally by SpartaDOS. 



Updates in the COMTAB Data Table 

Several updates to COMTAB locations have been made. For 
general information about COMTAB, refer to the SpartaDOS 
Construction Set Owner's Manual, pages 108-111. 

DWARM [COMTAB-21] 

This location contains a copy of the WARMFLG (location 
8) that will be used when a cartridge is entered; it indicates 
if user memory is valid and a indicates that a destructive 
command was entered (such as COPY) or that a binary file 
was loaded. 

DDENT [COMTAB-19] 

This is the table of bytes per sector for each drive (1-8). A 
indicates 256 bytes per sector and a 128 indicates 128 
bytes per sector. 

WARMST [COMTAB-1] 

NOT USED 

SBUFF [COMTAB + 28] 

This is the start address of SpartaDOS sector buffers. 

SMEMLO [COMTAB + 30] 

This is the top of SpartaDOS low memory. Handlers added 
since boot take up the memory between SMEMLO and 
MEMLO. 

INCOMND [COMTAB + 32 

A -1 here indicates that we are in the command processor 
(entering commands, etc.). A indicates that we are in 
BASIC or some cartridge program. This is used by the 
initialization routine to determine whether to enter the 
command processor or not. 
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Chapter 4— Update on Technical Structure 

Sparta DOS Version Identification 

When writing new commands, it is necessary to distinguish 
between versions of the DOS. From now on, two identification 
bytes at $700 and $701 are contained in ail versions (from 2.5 on). 
Location $700 will always contain a $53 and location $701 will 
contain the version number ($25, etc). 



Other Notes About Version 3.2 

Since the DOS initialization now gives control directly to the 
command processor (CP) if INCOMND is true (-1), the CP may 
inadvertently be entered when a user program performs a warm 
RESET (through $E474 vector). To avoid this, a -1 placed at 
memory location $702 will disable the initialization routine from 
running the CP. 



BASIC XE Notes 

To be compatible with BASIC XE, SpartaDOS could not use 
memory from $D800-$DFFF or $C000-$CBFF. However, normally 
SpartaDOS uses these areas: the first area for buffers and the 
second for both AINIT and the verbal error messages. Thus, when 
using BASIC XE: both the AINIT command and verbal error 
messages are disabled, and eight buffers are allocated just below 
MEMLO (increasing MEMLO by $400 bytes). The eight buffers are 
a decrease from the sixteen buffers normally maintained at 
$D800-$DFFF. 



Supra Hard Disk and Parallel Bus Notes 

To be compatible with the Supra Hard Disk Interface and any 
future parallel bus devices, it was necessary to vacate 
$D800-$DFFF (as with BASIC XE). Parallel bus use is determined 
and automatically compensated for by checking PDVMSK ($247) 
to see if any parallel devices are on line. If a device is present, 
DOS uses eight buffers at low memory and does not use 
$D800-$DFFF (therefore increasing MEMLO by $400). 
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CHAPTER 5— THE TIME/DATE 'Z:' HANDLER 
FUNCTIONS 



The following is a list of Time/Date 'Z:' handler functions and how 
to implement them from BASIC through XIO statements. The DOS 
command, if applicable, follows the function name in parenthesis. 



General Notes 

It is assumed that a 'Z:' handler has been installed into your 
system. This is accomplished by the command 'ZHAND' under 
SpartaDOS 3.2. (Also install the display with 'TDLINE' if using a 
display function under 3.2.) If using an earlier version of 
SpartaDOS or Atari DOS 2 (or versions thereof), you must use the 
'RTIME8.COM' file. Type 'RTIME8' if using a command processor 
driven DOS (like SpartaDOS), or rename the file to 'AUTORUN.SYS' 
and boot the diskette if using a DUP.SYS type of DOS (like Atari 
DOS 2.5.) 

Throughout these examples, 'IOCB' represents an Input/Output 
Control Block number from 1 through 7. 



Turn Time/Date Display ON (TD ON) 

Syntax 

XIO 38,#IOCB,0,0,"Z:" 

Notes 

An extra line will appear at the top of the display containing the 
current time and date. The SpartaDOS version number will also be 
displayed. If you are using the 'RTIME8' handler for Atari DOS 2, 
the message 'R-Time 8' will appear instead of the SpartaDOS 
version message. An error (139— Device NAK) will occur if the 
'TDLINE' handler has not yet been installed under SpartaDOS 3.2. 
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Chapter 5— The Time/Date 'Z:' Handler 

Turn Time/Date Display OFF (TD OFF) 

Syntax 

XIO 39,#IOCB,0,0,"Z:" 

Notes 

The extra line at the top of the display is removed. This has no 
effect on SpartaDOS's internal time keeping. 



Read Date (Formatted) 

Syntax 

XIO 34,#IOCB,0,0,"Z:" 
INPUT #IOCB,DATE$ 

Notes 

This sequence will read the date into 'DATES'. This string should 
be at least 13 characters long (as defined by the BASIC 'DIM' 
statement). The string will be returned in the format 'Mon 
21-Oct-85'. Attempts to read more characters will return an EOF 
error (error number 136). The IOCB must be opened for read prior 
to the execution of these statements (e.g. OPEN #1,4,0,"Z:"). An 
error 139 (NAK) will be returned if the TDLINE handler has not yet 
been installed when using SpartaDOS 3.2. 



Read Time (Formatted) 

Syntax 

XIO 32,#IOCB,0,0,"Z:" 

INPUT #IOCB,TIME$ 

Notes 

This sequence will read the time into 'TIMES'. This string should 
be at least 10 characters long (as defined by the BASIC 'DIM' 
statement). The string will be returned in the format '10:20:46am'. 
Attempts to read more characters will return an EOF error (error 
number 136). The IOCB must be opened for read prior to the 
execution of these statements (e.g. OPEN #1,4,0,"Z:"). An error 139 
(NAK) will be returned if the TDLINE handler has not yet been 
installed when using SpartaDOS 3.2. 
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Read Date (Unformatted) (DATE) 

Syntax 

XIO 35,#IOCB,0,0,"Z:" 

GET #IOCB,DAY : GET #IOCB,MONTH : GET #IOCB,YEAR 

Notes 

This sequence will read the numerical date into the variables: 
'DAY', 'MONTH', and 'YEAR'. The year is returned as the last two 
digits of the actual year (e.g. 1985 is returned as YEAR = 85). 
Attempts to read more characters will return an EOF error (error 
number 136). The IOCB must be opened for read prior to the 
execution of these statements (e.g. OPEN #1,4,0,"Z:"). No error will 
occur with this command under SpartaDOS 3.2 since this function 
is internal to the DOS. 

Read Time (Unformatted) (TIME) 

Syntax 

XIO 33,#IOCB,0,0,"Z:" 

GET #IOCB,HOUR : GET #IOCB,MINUTE : GET #IOCB,SECOND 

Notes 

This sequence will read the numerical time into the variables: 
'HOUR', 'MINUTE', 'SECOND'. The hour is returned using the 24 
hour clock where is midnight, 12 is noon, and 15 is 3 PM. 
Attempts to read more characters will return an EOF error (error 
number 136). The IOCB must be opened for read prior to the 
execution of these statements (e.g. OPEN #1,4,0,"Z:"). No error will 
occur with this command under SpartaDOS 3.2 since this function 
is internal to the DOS. 
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Set Time (TIME) 

Syntax 

XIO 36,#IOCB,0,0,"Z:" 

PUT #IOCB,HOUR : PUT #IOCB,MINUTE : PUT #IOCB,SECOND 

Notes 

This sequence will set the time from the variables: 'HOUR', 
'MINUTE', and 'SECOND'. The hour is given using the 24 hour 
clock where is midnight, 12 is noon, and 15 is 3 PM. Attempts to 
write more characters will return an EOF error (error number 136). 
The IOCB must be opened for write prior to the execution of these 
statements (e.g. OPEN #1,8,0,"Z:"). An error 139 (NAK) will occur if 
the handler is unable to set the time. The set function is an 
internal function of SpartaDOS 3.2. 



Set Date (DATE) 

Syntax 

XIO 37,#IOCB,0,0,"Z:" 

PUT #IOCB,DAY : PUT #IOCB,MONTH : PUT #IOCB,YEAR 

Notes 

This sequence will set the date from the variables 'DAY', 'MONTH', 
and 'YEAR'. The year is given as the last two digits of the actual 
year (e.g. 1985 is given as YEAR = 85). Attempts to write more 
characters will return an EOF error (error number 136). The IOCB 
must be opened for write prior to the execution of these 
statements (e.g. OPEN #1,8,0,"Z:"). An error 139 (NAK) will occur if 
the handler is unable to set the date. The set function is an 
internal function of SpartaDOS 3.2. 
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Chapter 5— The Time/Date 'Z:' Handler 

Some Examples Using the 'Z:' Handler 

The following program will keep a constant time display: 

10 DIM TIME$(13) : POKE 752,1 : REM turn cursor off 

20OPEN#1,4,0,"Z:" 

30XIO32,#1,0,0,"Z:" 

40 INPUT #1, TIMES 
50 POSITION 2,0 
60 PRINT TIMES 
70 GOTO 30 

Do not be alarmed if the time/date display line seems to stop 
while running this program. This is because both the TDLINE and 
the ZHAND routines try to use the SpartaDOS time/date vectors 
and priority is given to ZHAND rather than the interrupt display 
handling. If using the 'RTIME8' handler under Atari DOS or 
SpartaDOS 2.3 and earlier versions, there is no conflict. 
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CHAPTER 6-USING THE SUPRA HARD DISK 
INTERFACE WITH SPARTADOS 



Supra Corp. (formerly MPP) has released a parallel interface for 
hard disk drives (Winchester type). As previously promised, 
SpartaDOS is ready to be the DOS of choice for hard disk use. If 
you already have a Supra Hard Disk System up and running under 
another DOS, then skip the section on formatting and proceed to 
the section entitled "Configuring for SpartaDOS". If you are 
starting from scratch, then please read on. 



Formatting the Hard Disk 

The hard disk system stores important information about the type 
of hard drive being used on the first track of the disk. This 
information is written when the disk is formatted by the 
FORMWIN program. When the computer is powered-up, the 
interface tries to read this information. If the information is not 
present (your drive has not been formatted before), the interface 
assumes that the hard disk is not usable and turns the computer 
system back to normal (without a hard disk)! Thus, there are two 
methods to format the hard disk, depending on: 1) if the disk has 
already been formatted by FORMWIN (go to the "Configuring for 
SpartaDOS" section), or 2) not (read on). 

The first time the hard disk system is powered-up the hard disk is 
totally blank. Since the drive information is not present, the 
interface will disable the hard disk and attempt to boot off of 
floppy drive 1. (You must have a floppy drive set up as drive 1.) 

If this is not the first time (and the first track has not been 
trashed), the hard disk interface will attempt to boot from the 
'fake' floppy on the hard disk drive. If the system still needs to be 
booted from the floppy disk (set up as drive 2), hold down the 
<HELP> key while powering up the computer. This will allow the 
system to recognize the hard disk drive, but still boot from floppy 
disk drive 2. 
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Before powering-up the computer system, make sure there is a 
correct floppy disk drive attached and configured for drive 1 or 
drive 2 as per the information in the preceding paragraph. Turn on 
the hard disk sub-system and wait for it to come up to speed. 
Insert the SpartaDOS 3.2 master diskette into the correct disk 
drive. Remove all cartridges and hold down the < OPTION > key to 
disable BASIC. Turn the computer on (hold down the <HELP> key 
also if this is not the first time the system has been powered-up). 
If everything is correctly connected and turned on, the computer 
should boot from the floppy. 

The first step in setting up the hard disk system is to format the 
hard disk. Use the external command 'FORMWIN' (just type 
'FORMWIN < return >'). This program will ask for drive number or 
1; type '0 < return >'. The next prompt will ask for drive type (0 
through 8). Choose the drive type number from the following table 
that corresponds to the type of hard disk attached to the hard disk 
system. 



Number 


Size 


Type 


Specifications 



1 
2 
3 
4 


5 Meg 

5 Meg 

10 Meg 

10 Meg 

11 Meg 


ST-506 

TM-501/ST-706 

TM-502/ST-712 

ST-506 

TM-503 


153 Cyl/ 4 Hds 
320 Cyl / 2 Hds 
320 Cyl / 4 Hds 
230 Cyl / 6 Hds 
306 Cyl / 6 Hds 



(Select '2' if you have a Supra Corp. Hard Disk System.) 

The format program will warn you that all data on the hard disk 
will be lost; answer 'Y < return >'. The hard disk will be formatted 
and then verified for bad tracks. This process will take from 10 to 
20 minutes. 

When the format program is finished, turn only the computer OFF. 
Now attach a floppy disk drive configured as drive 2 and re-boot 
the computer while holding the< HELP > and < OPTION >keys 
down. Now you must configure the hard disk for SpartaDOS. 
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Configuring for SpartaDOS 

First, use the XINIT command to initialize drive 1 and write 
SpartaDOS 3.2 to it (the 'fake' floppy.) (You should first type 'D2: 
< return>' and then 'XINIT < return >' since the floppy is in drive 

2.) You should initialize the drive 1 portion of the hard disk as a 40 
track, single-sided, double-density drive. Answer 'N' to US sector 
skew. 

Next use the HDINIT command (type 'HDINIT < return >') to 

initialize drive 3 (the large portion of the hard disk). All that is 
required is a volume name and the drive number (3). Drive 4 will be 
initialized if you are using a second hard disk drive connected to 
your XEBEC controller board. 

Now the hard disk is totally configured and you should never have 
to initialize it again. Now re-boot the computer (do not hold down 
the <HELP> key, simply watch the speed as the DOS loads in). 



Using the Hard Disk 

The hard disk sub-system (the physical drive unit) is the only 
sensitive part of a hard disk system. When the hard disk sub- 
system is running it should never be moved or bumped. The heads 
in the hard disk are extremely close to the surface of the hard disk 
and any movement may cause the heads to hit the media surface 
causing a literal head crash. 

The hard disk system should be turned on in a specific sequence. 
First turn on the hard disk sub-system and wait for it to come up 
to speed (the motor sound should be steady). If the computer is 
turned on before the hard disk is ready, the computer will either 
try to boot off the floppy drive 1 or give 'BOOT ERROR'. To boot 
the computer from a floppy disk, put the diskette into disk drive 2 
and hold down the < HELP > key while turning the computer on. 
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The following is a description of the utility programs by Supra 
Corporation for use with the hard disk. 

FORMWIN This program formats and verifies the whole hard disk. 
LOCK1 This program write-protects the 'fake' floppy drive. 

OPEN1 This program un-write-protects the 'fake' floppy drive. 

LOCK34 This program write-protects hard disk drives 3 and 4. 

OPEN34 This program un-write-protects hard disk drives 3 and 4. 
ADDLF This program adds line-feeds to all carriage returns that 

are issued to the parallel printer port on the interface. 
RMVLF This program stops the adding of line feeds to carriage 

returns issued to the parallel printer port. 
PARK This program positions the heads at the innermost 

track. (A good practice before moving the hard disk 

system.) 



Some Notes About SpartaDOS 

You may also use the SpartaDOS commands: LOCK, UNLOCK, 
PROTECT, and UNPROTECT, to prevent accidental erasure of your 
files on the hard disk system. The BYPASS command from 
SpartaDOS allows the use of a floppy as drive 1. SpartaDOS will 
support 128 files per directory with an unlimited number of 
directories, and up to 16 megabytes as one drive. Use and enjoy. 
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